home *** CD-ROM | disk | FTP | other *** search
/ Night Owl 6 / Night Owl's Shareware - PDSI-006 - Night Owl Corp (1990).iso / 007a / cug315.zip / MOUSELIB.TXT < prev    next >
Text File  |  1990-05-16  |  8KB  |  176 lines
  1. DOCUMENTATION FOR MOUSELIB.C
  2.  
  3. Documentation dated 7/89
  4. Program and documentation Copyright (c) 1989, E.R.I.  All rights reserved.
  5.  
  6. INTRODUCTION
  7.      MOUSELIB.C is the source file for my front-end to the Microsoft mouse.  In
  8. order to use the functions in MOUSELIB.C, you must have installed MOUSE.SYS in
  9. your system and have a Microsoft (compatible) mouse.  MOUSE.SYS is installed as
  10. a device at boot-up.   You should have a line like DEVICE=MOUSE.SYS in your
  11. config.sys file.  See the mouse manual for details.
  12.      Since I support Microsoft (-like) mice only, I provide support for a two-
  13. button mouse only.  If you are using a three-button mouse like the logitech
  14. mouse, the two outside buttons are the ones that are used.  The middle button is
  15. not supported.  In general, I try to use the RIGHT mouse button as the
  16. functional equivalent of a carriage return.  If there is some special function
  17. that can be controlled by the mouse, that may utilize the LEFT button.  It is
  18. desirable to maintain consistency in how you utilize the mouse.
  19.      The mouse driver MOUSE.SYS supports "virtual screen" operation, in which
  20. the mouse position is scaled to the screen coordinates (use m_install() to
  21. initialize MOUSE.SYS for the current screen mode).  Alternatively, you may use
  22. the mouse in its "raw" mode, in which MOUSE.SYS reports change in mouse position
  23. in mickeys (use mdpos_read() for this).  A mickey is a unitless motion
  24. increment, and ranges from -32K to +32K.  I use the "raw" mode exclusively.
  25. There are three reasons for this.  First, I often use the mouse with frame-
  26. grabber display screens, which are not supported as virtual screens.  Second,
  27. our computer video adaptors are Hercules monochrome adaptors.  The MOUSE.SYS
  28. support for Hercules in virtual mode is the CGA 600x200 mode, which means that
  29. only part of the Hercules screen is mapped to virtual mouse coordinates.  And
  30. third, when I use the mouse in text mode, I use a different programming model
  31. than the MOUSE.SYS positional coordinates approach.  I define active fields on
  32. the screen, and mouse motion highlights the next active field in the direction
  33. of the mouse motion, instead of placing a cursor in an absolute row and column
  34. on the screen.
  35.      MENU.C is the arbitor of input style for my programs.  I call
  36. get_mouse_flag() from MENU.C in order to decide whether mouse operation should
  37. be supported in normal text entry or not.  See MENU.C and the MENU_DEM.C
  38. demonstration program for more discussion of this.  The functions inpause() and
  39. mouse_gets() in this module are used specifically for mouse support of text-
  40. screen operation.
  41.      When you link modules that use MOUSELIB.C, you must either use MOUSE.LIB
  42. from Microsoft (the version dated 1-23-89 or later will do.  What is important
  43. is that its large memory model c call must be cmousel().  Early versions of
  44. MOUSE.LIB used a pascal convention call, mouses() ).  If you do not have
  45. MOUSE.LIB, my MOUS_SYS.LIB will do the same thing, and may be substituted for
  46. MOUSE.LIB with these routines.  You should consult the book, Microsoft Mouse
  47. Programmer's Reference (Microsoft Press, 1989) for a full description of mouse
  48. programming parameters and MOUSE.SYS function calls.
  49.  
  50.  
  51. DATA STRUCTURES USED IN MOUSELIB.C
  52.      MOUSELIB.C uses one data structure, mstruc, defined in mouselib.h as
  53. follows:
  54.  
  55. typedef struct
  56. {
  57.      int opcode;
  58.      int status;
  59.      int dx;
  60.      int dy;
  61. } mstruc;
  62.  
  63. Most MOUSELIB.C functions return structs of type mstruc.  The meaning of each
  64. argument varies with the given function.
  65.  
  66. MOUSELIB.C EXTERNALLY-VISIBLE FUNCTIONS
  67.      The MOUSELIB.C externally-visible functions are declared and the mstruc
  68. typedef and various constants are defined in mouselib.h, which should be
  69. included in any program that uses these functions.
  70.  
  71. FUNCTION: button_clicks()
  72. TYPE: struct of type mstruc
  73. ARGUMENTS: one int.
  74.  
  75.      button_clicks(button) reads the number of button presses for button since
  76. the last call to button_clicks(button).  The arguments for button are: 1 = LEFT
  77. button, 2 = RIGHT button.  The values returned in the mstruc structure are:
  78. mstruc.opcode holds the current status of the specified button (0=not pressed,
  79. 1=pressed); mstruc.status holds the number of presses since the last call to
  80. this function (and this button.  You can inquire about one button without
  81. clearing the count for the other button).  mstruc.dx and mstruc.dy hold the
  82. mouse position in virtual screen coordinates at the time of the last button
  83. press.
  84.  
  85.  
  86.  
  87. FUNCTION: button_read()
  88. TYPE: struct of type mstruc
  89. ARGUMENTS: none.
  90.  
  91.      button_read() returns a struct of type mstruc that tells you the following:
  92. mstruc.status contains the current condition of the buttons (1=LEFT button is
  93. currently being pressed, 2=RIGHT button is currently being pressed, 3=BOTH
  94. buttons are currently being pressed), mstruc.dx and mstruc.dy report the
  95. position in virtual screen coordinates.  This function is most useful for mouse
  96. "drag" operations, in which an operation continues just as long as a button is
  97. depressed (see my area selection functions in the cut and paste routine or in
  98. the area greyscale stretch of NEW_SLO.EXE for examples).
  99.  
  100.  
  101.  
  102. FUNCTION: inpause()
  103. TYPE: int
  104. ARGUMENTS: none.
  105.  
  106.      c=inpause() is used to support mouse button presses in response to a pause
  107. with a "Press any key to continue"-style delay. It pauses until either a key is
  108. pressed or a mouse button is pushed, then returns the keypress value or ASCII
  109. 13 (<CR>) if the RIGHT mouse button was pressed, and ASCII 127 for either
  110. the LEFT button press or BOTH buttons.  inpause() is a substitute for getch()
  111. when you are using the mouse.
  112.  
  113.  
  114.  
  115. FUNCTION: m_install()
  116. TYPE: struct of type mstruc
  117. ARGUMENTS: none.
  118.  
  119.      m_install().status is a value that tells you whether the mouse and driver
  120. have been installed.  If the value is 0, they are not installed.  If -1, they
  121. are installed.  No other mstruc variable is used in this function.  A call to
  122. m_install() will also initialize MOUSE.SYS virtual screen for the currently
  123. active computer screen mode.
  124.  
  125.  
  126.  
  127. FUNCTION: mdpos_read()
  128. TYPE: struct of type mstruc
  129. ARGUMENTS: none.
  130.  
  131.      mdpos_read() returns an mstruc structure as follows:
  132. mstruc.dx and mstruc.dy are the x,y change in position of the mouse in mickeys
  133. (-32K to +32K) since the last mdpos_read() function call.
  134.  
  135.  
  136.  
  137. FUNCTION: mouse_clear()
  138. TYPE: void
  139. ARGUMENTS: none.
  140.  
  141.      mouse_clear() clears the buffers for the button_clicks() and mdpos_read()
  142. functions.  If a button is being held down during a mouse_clear() call, the
  143. routine waits one second and then beeps to let the user know that the button
  144. must be released.  mouse_clear() would normally be called at the beginning of a
  145. sequence, to put the counters in a known, reset state.
  146.  
  147.  
  148.  
  149. FUNCTION: mouse_gets()
  150. TYPE: character pointer
  151. ARGUMENTS: one string pointer
  152.  
  153.      mouse_gets(string) accepts as an argument a pointer to a character(s)
  154. buffer and allows a user to enter a string by keyboard.  The string input is
  155. terminated by either a carriage return or a RIGHT mouse button press.  It
  156. returns a pointer to string, which is null-terminated.  mouse_gets() operates
  157. exactly like gets(), except that it allows the RIGHT mouse button to operate as
  158. a carriage return.  The reason that this is useful is that many input strings
  159. allow the user to accept a default value by simply pressing <CR>.  Using
  160. mouse_gets() allows these functions to be performed without releasing the mouse.
  161.  
  162.  
  163.  
  164. FUNCTION: mouse_response()
  165. TYPE: struct of type mstruc
  166. ARGUMENTS: none.
  167.  
  168.      mouse_response() checks for mouse activity, and returns the following:
  169. mstruc.status returns 1 if the LEFT button has been pressed since the last call,
  170. 2 if the RIGHT button has been pressed, 3 if BOTH buttons have been pressed, or
  171. 0 if NO buttons have been pressed.  It does not return a button-press count for
  172. these buttons.  mstruc.dx and mstruc.dy are the change in mouse position since
  173. the last call to the function, SCALED by MOTION_FACTOR, which is a constant
  174. defined in mouselib.h.  mouse_response() is a composite function which calls
  175. both button_clicks() and mdpos_read(), so these functions will be reset by a
  176. call to mouse_response().